ScriptLink Technical Overview
-----------------------------
By Tim Hoffman, Technical Director, Momentum
Copyright 1994 Momentum. All rights reserved.

THIS ARTICLE WAS FIRST PUBLISHED IN PDA DEVELOPERS (FORMERLY PIE DEVELOPERS)
MAGAZINE. CONTACT CREATIVE DIGITAL SYSTEMS AT CDS@NETCOM.COM FOR MORE
INFORMATION. 

Until now, there has been no easy way for Newton developers to
interact with information on other platforms. Whilst the Newton
Connection Kit offers import and export facilities, it is clearly
aimed at the personal user. For the developer who wishes to query a
database or update a file from the Newton in realtime, the
alternative has been the painful process of building a solution from
scratch.

For the Newton developers working with Macintosh based systems, there
is now a solution. ScriptLink offers Newton developers a flexible
mechanism for controlling a server Macintosh using AppleScript.
Combining the flexibility of AppleScript with the mobile computing
power of the Newton, ScriptLink enables developers to quickly build
customised solutions using off the shelf software packages.
ScriptLink is compatible with industry standard wired and wireless
AppleTalk networks.

The ScriptLink Developer Kit is based on a powerful client server
architecture. The Macintosh based ScriptLink Server provides a
secure, multi-user environment in which AppleScript commands are
executed. The Newton based ScriptLink Client provides a high level
interface for developers of Newton applications, removing the
requirement to work directly with low level communications protocols.
Using ScriptLink, developers can eliminate the need to create
customised server software for each application, dramatically
reducing overall development time.

By using the power of AppleScript with third party applications,
ScriptLink enables easy access to data on other platforms. For
example, using an AppleScript database gateway, a Newton application
can access information in an Oracle database residing on a Unix
server, or across a Novell network to data used on a Windows system.

Potential applications
----------------------
Potential applications range from simple data transfer to vertical
market data capture and retrieval applications. Using the wide range
of AppleScript-aware applications available for the Macintosh, any
Newton developer can easily add remote communications, database
access and other facilities to their Newton application.

Beta testers have reported excellent results using ScriptLink to
control applications such as FileMaker Pro, 4th Dimension, HyperCard
and custom developed software.

Prerequisites
-------------
To use ScriptLink a Macintosh server with the following minimum
specifications is required.

1mb free RAM
1mb disk space
AppleTalk network connection
System 7.1
AppleScript 1.1

Generally, a 68040 based Macintosh server is recommended for the best
possible performance. ScriptLink is compatible with PowerMacintosh
systems.

The ScriptLink Client is a 30k Newton application which is installed
onto each Newton. The client supports all current Newton products.
Newton system v1.1 or later is recommended. An AppleTalk network
connection is required to communicate with the ScriptLink Server.

Developers should be familiar with both the Newton Toolkit and
AppleScript. Access to the Newton Toolkit v1.0.1 is required and
access to the AppleScript Developer Kit v1.1 is highly recommended.

How the ScriptLink Server works
-------------------------------
The ScriptLink Server provides a controlled environment for the
execution of AppleScript by multiple Newton clients. The status
window displays the name and network address of connected users, and
an onscreen diagnostics facility allows you to see exactly what is
happening at any time. An idle timeout facility allows you to
automatically logout users if they are inactive for a specified
period of time.

A variety of authentication options allows the developer to apply as
much or as little security as needed for different applications.
Authentication options include no authentication, a simple
username/password combination or a customised system using
AppleScript supplied by the developer. Custom authentication systems
could include access to other servers to validate usernames as
required.

The server can produce full logs showing all logins and logouts. A
diagnostics option assists the developer by logging the text of all
AppleScripts executed and results returned by the server.

Using ScriptLink with your Newton application
---------------------------------------------
The operation of ScriptLink is fully asynchronous. Whilst waiting for
a connection to occur or AppleScript code to be executed, the Newton
application may continue its own processing as required. The
developer interacts with ScriptLink using three main calls.

SLConnect opens a connection to the ScriptLink Server, specifying a
network address, username and password.

SLDisconnect closes the connection to the ScriptLink Server.

SLSendScript sends an AppleScript to be executed.

Two further calls provide information about your current connection
to the server at any time. SLTransOutstanding allows the application
to check  if the current script is completed. SLConnectionStatus
returns the status of the connection to the server

ScriptLink uses the following callbacks inside the Newton application
to indicate the completion of a transaction.

SLConnectDone indicates the connection has been opened.

SLDisconnectDone indicates the connection has been closed.

SLScriptReturned is called when data is returned as the result of the
execution of an AppleScript.

An example application
----------------------
After designing your Newton application and installing the required
Macintosh applications,  the developer can develop a standalone
AppleScript to perform the required functions and test it using the
Script Editor. This script will later be used inside the Newton
application.

The developer can then create a new project in the Newton Toolkit and
design the appropriate views for the application. ScriptLink will
require the following callback slots defined in your application:

SLConnectDone
SLDisconnectDone
SLScriptReturned

When your application needs to connect to ScriptLink, you first need
to check that the client is loaded, then clone a copy of the
ScriptLink Client for your own use.

In this example, we use sl as the handle to the cloned copy of
ScriptLink.

if sl = nil then
   if HasSlot(GetRoot(),'|ScriptLink:MOMENTUM|) then
    sl:=Clone(GetRoot().|ScriptLink:MOMENTUM|._proto);
else begin
    EnsureInternal(
        GetRoot():Notify(kNotifyAlert, kApptitle,
                     "ScriptLink Client not loaded"));
end;

Next, choose the ScriptLink Server which you wish to connect to over
the network. This can be achieved via a hardcoded AppleTalk address
or by using the Newton chooser as shown below.

GetRoot().NetChooser:openNetChooser(nil,
    "=:ScriptLink@",nil,self,
    "Connect","ScriptLink Server","");

The Newton chooser will then call a method defined in your
application called NetworkChooserDone.  Once an address is
successfully defined, use SLConnect to connect to the ScriptLink
Server and test for a successfully initialised connection as follows:

if sl:SLConnect({caller: base,
        server: server,
        username:"peter",
        password:"test",
        title: "Tester",
        debug: nil,
        poweroff: nil
        })

    then EnsureInternal(
        GetRoot():Notify(kNotifyAlert, kApptitle,
                     "Connection Initialisation Failed!"));

On login to the server the callback SLConnectDone will be invoked,
enabling the application to indicate a successful or unsuccessful
login.

Once SLConnectDone has been called, send the first AppleScript to the
ScriptLink Server using SLSendScript. Special characters need to be
escaped as shown below.

TestScript:="set result to \"hello world\"\n";

sl:SLSendScript({script: TestScript , client_tag: nil});

Alternatively, you could define an entire text slot as an AppleScript
code fragment and send this.

The application will be notified of the result of the AppleScript by
using the SLScriptReturned callback. SLScriptReturned takes one
argument.

func(x)    //SLScriptReturned

begin
    if x.status = 0 then
    begin
        :SLSetStatus("Received - [" & x.data & "]");
    end
    else if x.status = 4 then
    begin
        EnsureInternal(GetRoot():Notify(
        kNotifyAlert, kApptitle,
        "Script Error returned from ScriptLink Server"))
    end;
end

Finally, close the connection to the ScriptLink Server using
SLDisconnect.

sl:SLDisconnect(nil);

What is in the ScriptLink Developer Kit?
----------------------------------------
Full developer documentation and a range of sample applications are
included in the ScriptLink Developer Kit. The samples use the
Scriptable Text Editor and FileMaker Pro to illustrate the basic
concepts of ScriptLink.

Availability
------------
The ScriptLink Developer Kit is currently available.
Additional copies of the ScriptLink Server and Client software are
also available for use in end-user sites where applications are
deployed. The ScriptLink technology can be licensed for inclusion
with commercial software.

Plans for future releases of ScriptLink include a PowerPC native
version of the server, support for serial, wireless, modem and infra-red
connections, and support for multiple OSA compliant scripting
languages.

Recommended pricing
-------------------
Part#   Description                                     $US             

SLK001  ScriptLink Developer Kit                        $450            
        ScriptLink Macintosh Server (1 licence)                              

        ScriptLink Newton Client (10 licences)                               

        Developer documentation                               
        Sample applications                           
        12 months technical support                           

SLS001  ScriptLink Server pack                          $300            
        ScriptLink Macintosh Server (1 licence)                              

        ScriptLink Newton Client (10 licences)                               


SLC010  ScriptLink Newton Client 10 licence pack        $150            
                                                
SLC050  ScriptLink Newton Client 50 licence pack        $600            

Site and volume licences are also available.

Distributors
------------
ScriptLink is available from the following companies.

Momentum Pty Ltd
Perth, Australia
Phone +61 9 483 2649
Fax +61 9 227 5447
Internet momentum@dialix.oz.au
AppleLink MOMENTUM.AUS

Momentum Pty Ltd is a privately held Western Australian company that
develops, markets and distributes mobile computing technologies.
ScriptLink is the first in a family of Newton connectivity solutions
from Momentum.

Creative Digital Systems
San Francisco, USA
Phone 415.621.4252
Fax 415.621.4922
cds@netcom.com
74774.50@compuserve.com

Creative Digital Systems is the publisher of PDA Developers magazine,
a technical journal for PDA developers, and a leading publisher and
distributor of PDA developer tools.

---

ScriptLink is a trademark of Momentum Pty Ltd. Macintosh is a
registered trademark of Apple Computer, Inc.  AppleScript, AppleTalk,
MessagePad and Newton are trademarks of Apple Computer, Inc. All
other corporate, brand, product and service names are trademarks of
their respective holders. Mention of third party products is for
informational purposes only and constitutes neither an endorsement
nor a recommendation.

Copyright 1994 Momentum.
